.TH std::span 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::span \- std::span

.SH Synopsis
   Defined in header <span>
   template<

       class T,                                  \fI(since C++20)\fP
       std::size_t Extent = std::dynamic_extent

   > class span;

   The class template span describes an object that can refer to a contiguous sequence
   of objects with the first element of the sequence at position zero. A span can
   either have a static extent, in which case the number of elements in the sequence is
   known at compile-time and encoded in the type, or a dynamic extent.

   For a span s, pointers, iterators, and references to elements of s are invalidated
   when an operation invalidates a pointer in the range [s.data(), s.data() +
   s.size()).

   Every specialization of std::span is a TriviallyCopyable type. (since C++23)

   A typical implementation holds a pointer to T, if the extent is dynamic, the
   implementation also holds a size.

.SH Template parameters

   T      - element type; must be a complete object type that is not an abstract class
            type
   Extent - the number of elements in the sequence, or std::dynamic_extent if dynamic

.SH Member types

   Member type                   Definition
   element_type                  T
   value_type                    std::remove_cv_t<T>
   size_type                     std::size_t
   difference_type               std::ptrdiff_t
   pointer                       T*
   const_pointer                 const T*
   reference                     T&
   const_reference               const T&
                                 implementation-defined LegacyRandomAccessIterator,
   iterator                      ConstexprIterator, and contiguous_iterator whose
                                 value_type is value_type
   const_iterator (since C++23)  std::const_iterator<iterator>
   reverse_iterator              std::reverse_iterator<iterator>
   const_reverse_iterator (since std::const_iterator<reverse_iterator>
   C++23)

   Note: iterator is a mutable iterator if T is not const-qualified.

   All requirements on the iterator types of a Container apply to the iterator type of
   span as well.

   Member constant

   static constexpr std::size_t extent = Extent;  \fI(since C++20)\fP

.SH Member functions

   constructor           constructs a span
                         \fI(public member function)\fP
   operator=             assigns a span
                         \fI(public member function)\fP
   destructor            destructs a span
   (implicitly declared) \fI(public member function)\fP
.SH Iterators
   begin                 returns an iterator to the beginning
   cbegin                \fI(public member function)\fP
   (C++23)
   end                   returns an iterator to the end
   cend                  \fI(public member function)\fP
   (C++23)
   rbegin                returns a reverse iterator to the beginning
   crbegin               \fI(public member function)\fP
   (C++23)
   rend                  returns a reverse iterator to the end
   crend                 \fI(public member function)\fP
   (C++23)
.SH Element access
   front                 access the first element
                         \fI(public member function)\fP
   back                  access the last element
                         \fI(public member function)\fP
   at                    access specified element with bounds checking
   (C++26)               \fI(public member function)\fP
   operator[]            access specified element
                         \fI(public member function)\fP
   data                  direct access to the underlying contiguous storage
                         \fI(public member function)\fP
.SH Observers
   size                  returns the number of elements
                         \fI(public member function)\fP
   size_bytes            returns the size of the sequence in bytes
                         \fI(public member function)\fP
   empty                 checks if the sequence is empty
                         \fI(public member function)\fP
         Subviews
                         obtains a subspan consisting of the first N elements of the
   first                 sequence
                         \fI(public member function)\fP
                         obtains a subspan consisting of the last N elements of the
   last                  sequence
                         \fI(public member function)\fP
   subspan               obtains a subspan
                         \fI(public member function)\fP

.SH Non-member functions

   as_bytes          converts a span into a view of its underlying bytes
   as_writable_bytes \fI(function template)\fP
   (C++20)

   Non-member constant

   dynamic_extent a constant of type std::size_t signifying that the span has dynamic
   (C++20)        extent
                  (constant)

   Helper templates

   template< class T, std::size_t Extent >
   inline constexpr bool ranges::enable_borrowed_range<std::span<T,       \fI(since C++20)\fP
   Extent>> = true;

   This specialization of ranges::enable_borrowed_range makes span satisfy
   borrowed_range.

   template< class T, std::size_t Extent >
   inline constexpr bool ranges::enable_view<std::span<T, Extent>> =      \fI(since C++20)\fP
   true;

   This specialization of ranges::enable_view makes span satisfy view.

   Deduction guides

.SH Notes

   Specializations of std::span are already trivially copyable types in all existing
   implementations, even before the formal requirement introduced in C++23.

         Feature-test macro         Value    Std                 Feature
   __cpp_lib_span                  202002L (C++20) std::span
                                   202311L (C++26) std::span::at
   __cpp_lib_span_initializer_list 202311L (C++26) Constructing std::span from a
                                                   std::initializer_list

.SH Example

   The example uses std::span to implement some algorithms on contiguous ranges.


// Run this code

 #include <algorithm>
 #include <cstddef>
 #include <iostream>
 #include <span>

 template<class T, std::size_t N>
 [[nodiscard]]
 constexpr auto slide(std::span<T, N> s, std::size_t offset, std::size_t width)
 {
     return s.subspan(offset, offset + width <= s.size() ? width : 0U);
 }

 template<class T, std::size_t N, std::size_t M>
 constexpr bool starts_with(std::span<T, N> data, std::span<T, M> prefix)
 {
     return data.size() >= prefix.size()
         && std::equal(prefix.begin(), prefix.end(), data.begin());
 }

 template<class T, std::size_t N, std::size_t M>
 constexpr bool ends_with(std::span<T, N> data, std::span<T, M> suffix)
 {
     return data.size() >= suffix.size()
         && std::equal(data.end() - suffix.size(), data.end(),
                       suffix.end() - suffix.size());
 }

 template<class T, std::size_t N, std::size_t M>
 constexpr bool contains(std::span<T, N> span, std::span<T, M> sub)
 {
     return std::ranges::search(span, sub).begin() != span.end();
 }

 void println(const auto& seq)
 {
     for (const auto& elem : seq)
         std::cout << elem << ' ';
     std::cout << '\\n';
 }

 int main()
 {
     constexpr int a[]{0, 1, 2, 3, 4, 5, 6, 7, 8};
     constexpr int b[]{8, 7, 6};
     constexpr static std::size_t width{6};

     for (std::size_t offset{}; ; ++offset)
         if (auto s = slide(std::span{a}, offset, width); !s.empty())
             println(s);
         else
             break;

     static_assert(""
         && starts_with(std::span{a}, std::span{a, 4})
         && starts_with(std::span{a + 1, 4}, std::span{a + 1, 3})
         && !starts_with(std::span{a}, std::span{b})
         && !starts_with(std::span{a, 8}, std::span{a + 1, 3})
         && ends_with(std::span{a}, std::span{a + 6, 3})
         && !ends_with(std::span{a}, std::span{a + 6, 2})
         && contains(std::span{a}, std::span{a + 1, 4})
         && !contains(std::span{a, 8}, std::span{a, 9})
     );
 }

.SH Output:

 0 1 2 3 4 5
 1 2 3 4 5 6
 2 3 4 5 6 7
 3 4 5 6 7 8

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to          Behavior as published              Correct behavior
                       it was unclear when the pointers,
   LWG 3203 C++20      iterators, and                           made clear
                       references to elements of span are
                       invalidated
   LWG 3903 C++20      the declaration of span's destructor was removed the declaration
                       unnucessary
   P2325R3  C++20      a span of non-zero static extents was    any span is a view
                       not a view

.SH See also

   mdspan            a multi-dimensional non-owning array view
   (C++23)           \fI(class template)\fP
   ranges::subrange  combines an iterator-sentinel pair into a view
   (C++20)           \fI(class template)\fP
   initializer_list  creates a temporary array in list-initialization and then
   \fI(C++11)\fP           references it
                     \fI(class template)\fP
   basic_string_view read-only string view
   \fI(C++17)\fP           \fI(class template)\fP
